Shareware Grab Bag/Shareware Grab Bag.iso/007/d86v223.arc/COMMANDS.DOC

Text File | 1987-04-08 | 8KB | 168 lines

---COMMANDS.DOC---

Debugger Command Language

In addition to immediate-execution assembly-language commands,
there is a set of commands recognized by the debugger.  They are
identified by the first keyword on the line being a single letter
(i.e., the second character of the line is a non-letter, usually
a comma or ENTER).


General Operands to Debugger Commands

Most of the debugger commands consist of their single-letter
identifier, followed by a comma, followed by one or more general
operands, separated by commas.  General operands can be one of
the following:

   a. a numeric constant, whose format is just as in the assembly
      language (leading zero means default hex, otherwise default
      decimal)
   b. a register name
   c. a user-symbol from the assembly-language program being
      debugged.


Format of Debugger Command Examples

Many of the examples given below will be given in double-quotes.
Note that the double-quotes are not part of the command.  You are
encouraged to try out the example on the debugger, by typing the
string within the quotes, not including the quotes, and always
followed by the ENTER key. Note further that the double-quoted
string may be broken across two lines of this manual, but that
does not mean you should type a ENTER where the string is broken-
-debugger commands always consist of a single line, always
terminated by ENTER.


The Debugger Command Set

Following is a description of the debugger commands recognized:

B  sets and clears the fixed breakpoints of the program.  The
   debugger has four breakpoints.  Two are transitory; they are
   automatically cleared after each return from the program to
   the debugger.  They can be set by the G command. The other two
   are fixed-- they will remain in effect until you explicitly
   clear them.  The fixed breakpoints are controlled by this B
   command.

   You follow the B with zero, one, or two general operands.  If
   there are zero operands (the B is followed immediately by a
   ENTER), then both fixed breakpoints are cleared.  If there are
   one or two operands, then the fixed breakpoints are set to the
   operands.

   Note that previously-set breakpoints can be implicitly
   cleared, by overwriting them with other breakpoints.  If your
   B command has one operand, and there was one breakpoint
   previously set, the debugger sets the unused breakpoint, so
   that both remain in effect.  If your B command has one
   operand, and both breakpoints were previously set, the most
   recently-set breakpoint is saved, and the older breakpoint is
   overwritten.

   Examples: if you type "b,numout", the debugger will set a
   breakpoint at location NUMOUT, which should be a label in the
   program being debugged. You may start and stop the program
   many times, the the breakpoint will stay there.  You may even
   allow the program to stop at NUMOUT repeatedly; the breakpoint
   is not cleared even if the program stops there.  If you
   subsequently type the command "b,01000", then there will be
   breakpoints at both NUMOUT and location hex 01000.  If you
   then type "b,01200", the first breakpoint NUMOUT is
   overwritten; the two breakpoints now in effect are 01000 and
   01200.  The 01000 breakpoint will be next in line to be
   overwritten.  You may clear both breakpoints by typing "b".
   There is no way to clear one breakpoint at a time.

F  finds a string of memory bytes.  The memory to be searched
   starts at the current CS:IP location.  The string being
   sought contained in memory at the CS:IP location marked with
   the last Shift-F7 command.  The number of bytes in the target
   string is given as the first operand to the F command.  For
   example, F 1 finds the next instance of a single byte value
   after the current CS;IP.  If the marked location points to a
   NOP, F 1 will find the next NOP code.

   If you provide a second operand to F, it is a "retreat
   number".  For example, F 2,10 assumes that you are looking for
   a 2-byte sequence, and you have retreated 10 bytes from the
   starting location for your search.  When the string is found,
   F will retreat 10 bytes from that string.  That way you can
   view the instructions that preceded the found string.  I use
   feature when I am searching for BIOS and DOS interrupt calls
   in a program.  I want to retreat before the calls, to see what
   function numbers were loaded into registers.  I can use the F3
   key to repeat the searches, giving me a sequence of
   disassembly displays with the interrupt in the middle.

   F with no operands returns CS:IP to the marked location, in
   case you want to use F7 to deposit another string to be
   searched.

   If you have never pressed Shift-F7 in this session, the marked
   location is 0C000 of the program's starting segment.  That's
   often a good "scratchpad" area for small programs, far from
   both the program and the stack.

G  starts the user program.  If there are no operands, then G is
   equivalent to the ctrl-G command.  You can give one or two
   operands to G, specifying locations within the program at
   which you wish to return to the debugger. These are
   "transitory breakpoints"; they are cleared when the program
   returns to the debugger for any reason.

   Whenever you start the program, at least one instruction from
   the program will be executed, even if there is a breakpoint at
   the current instruction pointer location.  This means you can
   set a breakpoint at the current location; instructing the
   program to return to the debugger the next time it gets back
   to the current location.


J  jumps to the location indicated by the operand, within the
   current code segment.  J is useful when you are exploring
   memory outside of your program's memory area.  In that case,
   the immediate JMP command is executed from a buffer within
   your program's original code segment.  JMP would therefore
   return you to that segment. J will keep you in the distant
   segment.


O  sets a special fixed breakpoint.  Whenever your program calls
   MSDOS via INT 33, the debugger will monitor the function
   number passed in the AH register.  If the function number
   falls within the range specified by this command, the program
   will trap back to the debugger.  If you give two operands to
   O, the operands are the lower and upper bounds for the range
   of trapped functions.  If you give one operand, only that
   function-number will be trapped.  If you give no operands, any
   previous O-trap setting is cleared.

   For example, note that function 3F hex is the READ function
   for MSDOS version 2.  If you want to trap whenever this READ
   function is invoked, you can issue the command O,03F and then
   start up your program with the G command.  Another example:
   suppose you want to insure that a program does not make any of
   the new Version 3 DOS calls, 59 hex and above.  You can issue
   the command O,059,0FF and then start your program.

   NOTE: if the second operand is less than the first, then the
   range wraps around through zero.  For example, O,059,030 traps
   on 059 through 0FF, and also 0 through 030-- both version 3
   and version 1 calls.

   SECOND NOTE: The EXIT function, hex 4C is always trapped by
   D86, regardless of your O-command settings.  The only way you
   should be able to exit from D86 is via the Q-command.  (If you
   do succeed in exiting some other way, I want to hear about it.
   In that case, D86 will become very confused if you reinvoke it
   before rebooting the computer.)


Q  exits the debugger and goes back to the operating system.